home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-11 / grumptem.zip / GENGRUMP.DOC < prev    next >
Text File  |  1993-01-04  |  21KB  |  476 lines
  1.           GENGRUMP TEMPLATE
  2.               ----------------
  3.  
  4. The only difference between this template and General.tem is that it has
  5. hooks in it for calling the Grumpfish Popup routines and the Grumphelp
  6. library.  The grumpfish modifications will only work if you are generating
  7. Clipper Summer 87 code.  If you say yes to generate Grumpfish stuff and you
  8. have flavor set to anything else, it gives you a message saying that you
  9. can't do it.  It will generate anything general.tem will.
  10.  
  11. If you want to standarize on this, you can rename this file to general.tem
  12. and renam stdgrump.tlb to stdfuns.tlb and do a global search and replace in
  13. this template for stdgrump and replace it with stdfuns
  14.  
  15. I hope you find this little modification usefull.  All of the credit should
  16. however go to Greg Lief of Grumpfish, Inc. for providing us with his
  17. wonderful Grumpfish Libraries in the first place.
  18.  
  19.  
  20.             Introduction
  21.             ------------
  22. Summary
  23. -------
  24.     This template is intended to be a "single-stop" for most program
  25.     generation.
  26.  
  27. Features
  28. --------
  29.     GENERAL can generate:
  30.        *   Help screens,
  31.        *   Menus,
  32.        *   Edit screens,
  33.        *   Add screens,
  34.        *   Delete screens,
  35.        *   Browse screens,
  36.        *   Search screens,
  37.        *   Any combination of the above,
  38.        *   All of the above (except menus) with multiple pages.
  39.        *   All of the above with popup menus.
  40.  
  41.    Structure of Generated Code.
  42.     Mostly, GENERAL structures the generated code into a main part
  43.     and ancilliary procedures to support the main functions.
  44.  
  45.     GENERAL can structure the code as:
  46.        *   a single, stand-alone program,
  47.        *   as a single sub-program file,
  48.        *   a PRG file with the ancilliary part in a separate procedure file,
  49.        *   the whole in the form of procedures in a procedure file.
  50.        *   In all cases where generation is to a procedure file, the
  51.        new code may be optionally appended to an existing
  52.        procedure file.
  53.  
  54.     GENERAL allows:
  55.       *    Multi-user code with record locking only on file updates,
  56.       *    Multi-user code with "safety" record locking when a record
  57.        is accessed for editing.
  58.       *    The main record locking function can be shared with other
  59.        parts of the system and is generated upon your request.
  60.       *    Embedded READ's by optionally simulating a single READ
  61.        statement with a separate READ statement for each @..GET.
  62.  
  63. Templates Obsoleted by GENERAL
  64. ------------------------------
  65.     GENERAL replaces the following templates on the version 1.00 diskettes:
  66.        BASIC.TEM
  67.        BASIC@P.TEM
  68.        DOAPPEND.TEM
  69.        DOEDIT.TEM
  70.        MAINMEN.TEM
  71.        MAINMN@P.TEM
  72.        MPAPPEND.TEM
  73.        MPBAS.TEM
  74.        MPBAS@P.TEM
  75.        MPEDIT.TEM
  76.        POPMEN3P.TEM
  77.        POPMENS.TEM
  78.  
  79. Examples
  80. --------
  81. WALLCUST.WW
  82.     Straightforward data screen with menu.    If you want to see
  83.     this example with a popup menu, take the cursor to the menu
  84.     box, type Ctrl-PgDn and type 'P' to toggle the popup-flag.
  85.  
  86. WALLMP.WW
  87.     Multi-page data screen with popup-menu.  When you run the
  88.     generated programm you can type PgUp/PgDn at any point to
  89.     switch pages.
  90.  
  91. WALLMP2.WW
  92.     Similar to WALLMP but has a shorter menu overlapping the
  93.     data display pages.
  94.  
  95. WALLMENU.WW
  96.     A pure menu with no data fields.
  97.  
  98. WALLPOPM.WW
  99.     A pure pop-up/pop-down menu.
  100.  
  101.     To see this in action, load WALLCUST.WW, go to the "GOTO"
  102.     option, use F7:MENU and revise its definition.    Replace the
  103.     action code with:
  104.         DO UPS
  105.     Change the trigger character to "U" and, after exiting the
  106.     F7:Menu, change the prompt to "UPS".  Generate as a main
  107.     program with procedures in the same file.  Now load
  108.     WALLPOPM.WW and generate.  When it asks you to confirm the
  109.     name, enter any false name.  When GENERAL asks if you want a
  110.     main program generated, answer "No".  Answer "Yes" to
  111.     generating into a procedure file.  When GENERAL asks you for
  112.     a file, give it the same name as you gave when you generated
  113.     from WALLCUST, then specify that you want code to be appended
  114.     to this file.  That's important, otherwise you'll lose the
  115.     code generated from WALLCUST.  When you're asked for the name
  116.     of the main procedure, enter "UPS".  You've now created a
  117.     small system using two separate pieces.
  118.  
  119. Program Linkages
  120. ----------------
  121.     GENERAL's generality is designed to allow you to generate a system
  122.     gradually, in small pieces.  The entire system can be pieced
  123.     together using the menus generated by GENERAL.  Validation functions
  124.     can also be used for linkages to verification functions.
  125.     Validation functions may do lookups on DBF's and can even perform
  126.     editing or record adding to DBF's.
  127.  
  128.                How to use GENERAL
  129.                ------------------
  130. Summary.
  131. -------
  132.     GENERAL's objective is to decide what to do as much as possible
  133.     from the form design.  For instance, if GENERAL finds no fields
  134.     in the form it assumes you want to generate either a pure menu or
  135.     a text-display screen (such as a help screen).  If it finds both
  136.     fields and menu options on the screen, it assumes you want a
  137.     multi-function data screen.
  138.  
  139. Menus.
  140. -----
  141.     GENERAL's simplest task is to generate a text-display module.
  142.     All you need do is draw your boxes, arrows, text, etc. and
  143.     generate.  The next simplest generation is that of a pure menu.
  144.     Design your form with just a menu and no fields.  If GENERAL
  145.     finds that it can use special language features to generate your
  146.     menu, it will use them.  For example, when generating for Clipper
  147.     or Fox+, if all your menu options are only one line high, GENERAL
  148.     will generate @..PROMPT code.  Likewise, in dBASE IV generation,
  149.     GENERAL would use ON SELECTION PAD code provided no option
  150.     (except the QUIT option) had more than a single action.
  151.  
  152. Menu Actions
  153. ------------
  154.     There are two types of actions that you can specify in the action
  155.     code for a menu option:  straight Dbase code or special keywords
  156.     recognized by GENERAL.
  157.  
  158.     The most important keyword is QUITMENU.  This tells GENERAL which
  159.     option quits the menu and allows GENERAL to generate appropriate
  160.     code to exit the menu.  Always insert the QUITMENU keyword as the
  161.     last action in the quit menu option.  For dBASE IV users, the
  162.     QUITMENU keyword has the added advantage that in the QUITMENU option
  163.     only, you can specify more than one action and GENERAL will still
  164.     generate the more compact ON SELECTION PAD code provided all other
  165.     options have only one action and all option prompts are only one
  166.     line high.
  167.  
  168.     One example of code you might want to insert with the QUIT option is:
  169.        SET COLOR TO W/N       && Reset color on exit to white on black
  170.        CLEAR           && Clear screen in this color
  171.        QUITMENU
  172.  
  173.  
  174.     If you combine a menu with a data screen (a screen containing
  175.     fields), GENERAL will assume that some menu options control actions
  176.     on the data screen.  In this case, GENERAL will check for other
  177.     keywords which stand for actions you want to perform on your data
  178.     screen.  These are:  EDIT, ADD, NEXT, PREVIOUS, FIRST, LAST, JUMP,
  179.     ERASE, and SEARCH.    These keywords are converted by GENERAL to the
  180.     appropriate Dbase code to perform these functions on your data
  181.     screen.
  182.  
  183.     The meanings of the keywords are:
  184.  
  185.     EDIT   -- edit current record(s)
  186.     ADD    -- append a new record to the active file(s)
  187.     NEXT   -- Skip forward to next record on the primary DBF
  188.           and display new values.
  189.     PREVIOUS -- Skip back one record on the primary DBF and
  190.           display new values.
  191.     FIRST  -- Skip to beginning of the primary DBF and display
  192.           values.
  193.     LAST   -- Skip to last record on the primary DBF and display
  194.           values.
  195.     JUMP   -- Go to specific record number and display values.
  196.     SEARCH -- Prompt for the value of a key to search on the
  197.           main index file of the primary DBF and display
  198.           all values if found, else restore prior record.
  199.  
  200. Menu Restrictions:
  201.     All options in your form must appear either in a single box or in no
  202.     box.  That is, if any option appears outside all boxes, then so must
  203.     all the others.  Likewise, if any option appears inside a box, then
  204.     so must all the others.  If, for any reason, you want extraneous
  205.     options in your form, then enclose the options for GENERAL to
  206.     process within a box called "MENU".  If you do that, then GENERAL
  207.     will ignore all other options outside the "MENU" box.
  208.  
  209. Note for dBASE IV Users.
  210.     GENERAL will use the the dBASE IV menu commands if it thinks that
  211.     they are appropriate.  That is, if all the menu prompts are only
  212.     one line high and no option has more than one action except possibly
  213.     the QUITMENU option.  However, version 1.0 of dBASE IV does not
  214.     handle certain menu processes correctly.  If you have any trouble
  215.     with dBASE IV menus, then you should request GENERAL to produce
  216.     generic menu code by placing the keyword "NOPADS" in any slot
  217.     of the menu box.
  218.  
  219. Popup Menus
  220. -----------
  221.     If your menu options are entirely contained inside a popup box, then
  222.     when the user chooses the Edit, Add, or Search options, the menu
  223.     disappears and reappears when editing is completed.
  224.  
  225.     If you are generating a pure menu which you have designated as a
  226.     popup then GENERAL will create code to restore the prior screen on
  227.     quitting the menu.
  228.  
  229. Data Screens
  230. ------------
  231.     If your form has no menu options, then GENERAL assumes that you have
  232.     a single-purpose data screen and asks you what that function is.
  233.     Your choices are:
  234.  
  235.        E - Edit, A - Add, D - Delete, S - Search.
  236.  
  237.     The module will be generated without a menu and when called, the
  238.     module will immediately go into the function you chose.  The user
  239.     can exit the module in the usual way -- by typing ^W or ^End to
  240.     save, or Esc to abandon.
  241.  
  242.     As explained above, if your screen has both a menu and a data
  243.     screen, GENERAL will search your options for the special keywords
  244.     which control actions on the data screen.  You can include other
  245.     actions if you wish;  these must be inserted as Dbase code.  You can
  246.     mix Dbase code and GENERAL's keywords in the same option provided
  247.     that GENERAL's keywords appear on their own option-action line.
  248.  
  249. Multi-Page Data Screens.
  250. -----------------------
  251.     Sometimes, a database has too many fields to fit on a single screen.
  252.     GENERAL can generate code for several pages of overlapping data
  253.     boxes.  These boxes are called "pages".  The pages may be arranged
  254.     any way you want.  The pages must be numbered.  Each page box must
  255.     have the keyword "page" in a general slot followed by a page number.
  256.     No two boxes can have the same number and you are limited to a
  257.     maximum page number of 10.
  258.  
  259.     Suppose you require three overlapping boxes to display all the
  260.     relevant fields in an application.    In any slot of the three boxes,
  261.     insert the word PAGE followed by the page number for that box.  So
  262.     in the first box, you would insert the text "PAGE 1" in one of its
  263.     slots, in the second box, "PAGE 2", and in the third, "PAGE 3".
  264.     Regardless of how you number the pages, the topmost page will be
  265.     the first displayed.
  266.  
  267.     The end user can flip from one page to another with the PgDn and
  268.     PgUp keys.    These are available to the user at all times until the
  269.     module is exited.  Only data in the currently topmost page is
  270.     displayed.    So, for example, if page 2 is currently the top page
  271.     then the values in the fields in the other boxes (boxes 1 and 3 in
  272.     our example) are not displayed.
  273.  
  274. Adding a new procedure to an existing program file.
  275. --------------------------------------------------
  276.     Using GENERAL, you can build systems gradually, in small pieces.
  277.     One way of doing this is to add procedures to an existing file
  278.     rather than making a new PRG file for every new module.
  279.     Unfortunately, to add to an existing file you need to lie to UI.
  280.     But it's a necessary lie.  When you start generation, UI displays a
  281.     file for you to confirm as the output file.  At this point, UI has
  282.     not fired up GENERAL and so UI is unaware that you might want to
  283.     append to an existing file.  So, at this point, enter a nonsense
  284.     file name.    UI will create this file and you can later delete it.
  285.     For instance, I enter a file name of X and when I'm done for the day
  286.     I delete X.PRG.
  287.  
  288.     GENERAL now gets control and asks you if you are generating a main
  289.     program.  You answer "No".    GENERAL then asks if you want to
  290.     generate into a procedure file.  Answer "Yes".  GENERAL will prompt
  291.     you for the name of the procedure file.  Now you can enter the real
  292.     name of the file, the file you want to append to.  GENERAL checks
  293.     that this file exists and if it does, asks you if you want to append
  294.     to it.  Of course, you answer "Yes".  Finally, GENERAL asks you what
  295.     name to give your main procedure.  It wants the name by which your
  296.     procedure will be called from outside this module.
  297.  
  298. Sample Dialog.
  299.     Here is an example of the dialog:
  300.  
  301.        UI:
  302.        Output file: D:\UI\PRG\MYFORM.PRG
  303.            You cancel this by typing,
  304.        Output file: X       (X.PRG is a file you later delete.)
  305.  
  306.        GENERAL:
  307.           Are you generating a main program (the first called)?
  308.        You: N           (No)
  309.  
  310.        GENERAL:
  311.           Do you want this module generated into a procedure file?"
  312.        You: Y           (Yes)
  313.  
  314.        GENERAL:
  315.           Name of procedure file:
  316.        You: MAINPROC       (Name of existing PRG file)
  317.  
  318.        GENERAL:
  319.           File exists.  Append to it?"
  320.        You: Y           (Yes)
  321.  
  322.        GENERAL:
  323.           Name of main procedure:
  324.        You: BROWSE           (Name by which your procedure
  325.                     is to be called)
  326.  
  327.  
  328. Multi-User Record Locking.
  329. -------------------------
  330.     If you go to UI's F10:Config menu and select the Generation
  331.     option.  You will see an option called: "generate Multi-user
  332.     code?".  If you set this option to YES then GENERAL will assume
  333.     you want record locking.
  334.  
  335.     GENERAL will generate record-locking code for all DBF's that are
  336.     about to be changed.  GENERAL, at your option, will generate the
  337.     record-locking test function called LOCK_TEST.  If you have already
  338.     generated part of your system and requested generation of the
  339.     LOCK_TEST function, then you should decline to generate it again
  340.     unless you are forced to do so to avoid SET PROCEDURE conflicts.
  341.     (Clipper users may need multiple copies of LOCK_TEST in order to
  342.     overcome overlay conflicts.)
  343.  
  344. Two Forms of Record Locking.
  345.     Two forms of record locking can be generated by GENERAL.  The
  346.     simplest is the lock during the actual update only.  The other is
  347.     record locking during an entire editing session.  The second is
  348.     safer than the first but is more liable to cause record freezing.
  349.     The LOCK_TEST function has a timeout and will interrogate the user
  350.     regarding what action to take in the event of a timeout.  There
  351.     follows two examples of record-locking with the different record-
  352.     locking options.
  353.  
  354. Example with Simple Locking.
  355.     Let's assume that there are two users, called A and B, on different
  356.     computers on the same network, both working on the same DBF file.
  357.     The DBF file contains several fields of which two are: LASTNAME
  358.     (character) and AMOUNT (numeric, dollars).    In our first example,
  359.     the two users are both running the same application which locks
  360.     records only for the actual record update.
  361.  
  362.     User A starts editing record 12, user B starts editing record 8.
  363.     Neither user is hindered since they are editing different records.
  364.     All is normal.  Now suppose they both start editing record 8
  365.     simultaneously.  So far there is still no hindrance since editing
  366.     begins by reading the existing data in record 8 and there is no
  367.     locking on record access, only on record update.  At this moment,
  368.     before either user has started editing, they are both looking at
  369.     exactly the same information.  Suppose user A just wishes to change
  370.     LASTNAME from "Jones" to "Smith".  He finishes ahead of user B, and
  371.     types Ctrl-W to save his screen.  Since both applications have
  372.     record locking only on update, the record update proceeds normally
  373.     because user B is still editing.  Meanwhile, user B has to change
  374.     AMOUNT from $100 to $1,000.  She finishes and saves the screen with
  375.     Ctrl-W.  This also proceeds normally.  Unfortunately, user A's
  376.     modification has been lost.  The record again contains "Jones" in
  377.     the LASTNAME field because that is what it contained when user B
  378.     accessed the record and therefore that is what is contained when
  379.     user B saves the record as user B did not change that field.
  380.  
  381. Example with Safety Locking.
  382.     User A and user B are again running the same application, but this
  383.     time the application has record locking specified for entire editing
  384.     sessions.  Now see what happens in the above situation.  User A is
  385.     the first to start editing record 8 and succeeds in retrieving the
  386.     current record since no one else is editing as yet.  User B now
  387.     tries to edit record 8, but cannot because the attempt to lock the
  388.     record at the beginning of the edit session fails since A already
  389.     has the record locked.  Consequently, the above situation where user
  390.     A lost changes cannot occur.
  391.  
  392. Calculated Fields.
  393. -----------------
  394.     GENERAL assumes that all calculated fields are to be calculated
  395.     after data entry but before record update.
  396.  
  397.     Whenever a screen contains calculated fields, GENERAL will generate
  398.     code to redisplay the screen after all data has been entered.  If
  399.     the application has a menu, there is no confirmation required.  The
  400.     edited record is still on the screen after the operator finishes
  401.     editing.  If there was an error, the operator can resume editing
  402.     immediately.  If the application consists of a single function, with
  403.     no menu, then confirmation is required after viewing the calculated
  404.     fields.
  405.  
  406. Validation Functions
  407. --------------------
  408.     You can enter validation functions in the Valid Slot in any field.
  409.     If you do, GENERAL will insert your function in the VALID clause on
  410.     that field.  There is no restriction on what the validation function
  411.     may do.  In particular, you may insert a data entry screen in the
  412.     validation.  For instance, if during a lookup, the user does not
  413.     find a desired record, you might allow the user to add a new record
  414.     at that point.
  415.  
  416. Embedded READ's.
  417.     However, if you do want data entry in the validation, you must
  418.     answer "yes" to GENERAL's question:  "Do any of your validation
  419.     routines use @..GET and READ?"  This will cause GENERAL to insert
  420.     a READ after every @..GET statement together with appropriate
  421.     code to control the cursor.
  422.  
  423. Generation modes.
  424. ----------------
  425.     You can suppress all of GENERAL's questions (though they are few) by
  426.     creating a box called PARAM which contains all your parameters.
  427.     Alternatively, you can place the answers in the slots of a box with
  428.     the word PARAM in slot1.  GENERAL will recognize the following in the
  429.     slots 1 to 5 of the parameter box:
  430.  
  431.      MAIN           Generate a main (top-level) program.
  432.  
  433.      MODULE           Generate a sub-PRG.
  434.  
  435.      PROCFILE <file>       Generate a procedure file.
  436.  
  437.      PROCNAME <name>       Name of top-level procedure (only if
  438.                PROCFILE is also specified.)
  439.  
  440.      SUBPROCS <file>       Generate separate procedure file for
  441.                supporting procedures.  (Valid only if
  442.                PROCFILE was NOT specified.)
  443.  
  444.      APPEND           (Only with SUBPROCS) Append to SUBPROCS
  445.                file.  (Otherwise, GENERAL will overwrite
  446.                any existing file.)
  447.  
  448.      EMBEDDED           Allow usage of @..GET's and READ in
  449.                validation functions.
  450.  
  451.      SCREEN LOCK       Only for multiuser applications:  Lock
  452.      SAFETY LOCK       entire edit sessions.
  453.  
  454.      UPDATE LOCK       Only for multiuser applications:  Lock
  455.                on record update.
  456.  
  457.      GENPROC           Generate the LOCK_TEST function.
  458.  
  459. Future Enhancements
  460. -------------------
  461.  
  462.     Scrolling lookups will be available in the LOOKUP.TEM file and
  463.     these can be linked in very easily to GENERAL-generated code.
  464.  
  465.     Detail record screens.
  466.        Screens which can show and allow editing and adding of
  467.        several records.
  468.  
  469.     Searches using the Dbase LOCATE command.
  470.  
  471.     Popup data screens.
  472.  
  473.     Popup simulation for dBASE III and QuickSilver.
  474. D
  475.  
  476.